<div id="pagecontainer">
    <table>
        <tr>
            <td width="5">
                &nbsp;</td>
            <td>
                <a name="Enhancement"></a>
                <br />
                <a name="outline227"></a>
                <br />
                <h1>
                    16. Enhancement</h1>
                <br />
                As we have seen both <a href="TransparentActivation.html#TransparentActivation">Transparent
                    Activation</a> and <a href="Query.html#NativeQueries">Native Queries</a> will
                produce correct results out-of-the-box.<br />
                <br />
                To get your application to run as fast as possible with db4o, you will want to make
                sure that only required objects are loaded from the database and that Native Queries
                are optimized to use field indexes where this is possible.<br />
                <br />
                Theoretically you could write all the necessary code by hand but you will save yourself
                a lot of time if you use automatic enhancement. Using the db4o enhancer tools you
                can automatically add code to your assemblies to make them work even better with
                db4o.<br />
                <br />
                There are two possible strategies to enhance your assemblies:<br />
                <a href="Enhancement.html#EnhancementMSBuild">Enhancement with MSBuild</a><br />
                <a href="Enhancement.html#EnhancementDb4oTool">Enhancement using Db4oTool</a><br />
                <br />
                <ul>
                    <a name="outline228"></a>
                    <br />
                    <h2>
                        16.1. Required Libraries</h2>
                    <br />
                    The db4o enhancer requires the following assemblies in order to work:<br />
                    <br />
                    <b>Cecil.FlowAnalysis.dll</b><br />
                    IL code flow analysis<br />
                    <br />
                    <b>Db4objects.Db4o.dll</b><br />
                    db4o core engine<br />
                    <br />
                    <b>Db4objects.Db4o.Instrumentation.dll</b><br />
                    IL code instrumentation<br />
                    <br />
                    <b>Db4objects.Db4o.NativeQueries.dll</b><br />
                    Native Query Analyzer<br />
                    <br />
                    <b>Db4oTool.exe</b><br />
                    commandline tool<br />
                    <br />
                    <b>Db4oTool.MSBuild.dll</b><br />
                    MSBuild tasks &nbsp;&nbsp;<br />
                    <br />
                    <b>Mono.Cecil.dll</b><br />
                    IL code handling<br />
                    <br />
                    <b>Mono.GetOptions.dll</b> &nbsp;<br />
                    helper library for Cecil<br />
                    <br />
                    <a name="EnhancementMSBuild"></a>
                    <br />
                    <a name="outline229"></a>
                    <br />
                    <h2>
                        16.2. Enhancement with MSBuild</h2>
                    <br />
                    When csc (or Visual Studio, calling csc) compiles your assemblies, it uses the instructions
                    in your csproj project files to know what to do. The "code" in csproj files is plain
                    XML, it is very well readable and you can add your own tasks to the build by editing
                    the files with your favourite (XML) editor.<br />
                    <br />
                    If you want the produced assemblies to be enhanced for db4o, you can add the db4o
                    enhancer build task to your csproj files as an "AfterBuild" task.<br />
                    <br />
                    Db4oTool.MSBuild.dll contains the main MSBuild enhancer task:<br />
                    Db4oTool.MSBuild.Db4oEnhancerMSBuildTask<br />
                    <br />
                    For all possibilities of using this task see the <a href="http://developer.db4o.com/Resources/view.aspx/Reference/Object_Lifecycle/Activation/Transparent_Activation_Framework"
                        target="_blank">&nbsp;topics on transparent activation</a> in the reference
                    documentation.<br />
                    <br />
                    The simplest enhancer task does both: It optimizes Native Queries and it adds the
                    IActivatable interface to your classes, making sure a persistent object is activated
                    whenever any field is read. Here is a simple example of how such an addition to
                    MSBuild task could look like:<br />
                    <br />
                    <table border="0" cellpadding="3" cellspacing="0" width="100%">
                        <tr>
                            <td class="lg">
                                <code>&lt;Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003"&gt;<br />
                                    <br />
                                    &nbsp; &lt;!--<br />
                                    &nbsp; &nbsp; Normal build code here &nbsp;&nbsp;<br />
                                    &nbsp; --&gt;<br />
                                    &nbsp;&nbsp;<br />
                                    &nbsp; &lt;UsingTask AssemblyFile="$(OutputPath)\Db4oTool.MSBuild.dll" TaskName="Db4oTool.MSBuild.Db4oEnhancerMSBuildTask"
                                    /&gt;<br />
                                    &nbsp; &lt;ItemGroup&gt;<br />
                                    &nbsp; &nbsp; &lt;Db4oEnhance Include="$(TargetPath)" /&gt;<br />
                                    &nbsp; &lt;/ItemGroup&gt;<br />
                                    &nbsp; &lt;Target Name="AfterBuild"&gt;<br />
                                    &nbsp; &nbsp; &lt;Db4oEnhancerMSBuildTask Assemblies="@(Db4oEnhance)" /&gt;<br />
                                    &nbsp; &lt;/Target&gt;<br />
                                    &nbsp;&nbsp;<br />
                                    &lt;/Project&gt;</code></td>
                        </tr>
                    </table>
                    <br />
                    <br />
                    <a name="EnhancementDb4oTool"></a>
                    <br />
                    <a name="outline230"></a>
                    <br />
                    <h2>
                        16.3. Enhancement using Db4oTool</h2>
                    <br />
                    Db4oTool.exe is a top level command line interface to all enhancement tasks. You
                    can either add it to your own build setup or you can directly integrate it from
                    within Visual Studio.<br />
                    <br />
                    To get you an idea on how you can set things up, here is a step-by-step example
                    how you could integrate Db4oTool.exe from Visual Studio.NET 2005 to do it's post-build
                    tasks for a CompactFramework 2.0 project:<br />
                    <br />
                    - In Visual Studio, right click on the project you want to enable Native Query optimization
                    for<br />
                    - Select <b>'Properties'</b><br />
                    - In the Properties Page select the <b>Build Events</b> tab<br />
                    - In the <b>Post-build event command line</b> text box insert the following text:<br />
                    <b>
                        <path-to-your-db4o-installation>
</path-to-your-db4o-installation>
                        /bin/Db4oTool.exe -ta -nq $(TargetPath)</b> (replace
                    <path-to-your-db4o-installation>
</path-to-your-db4o-installation>
                    with the correct path for your system)<br />
                    <br />
                    Db4oTool.exe offers different command line options for different setups. You can
                    get a list of options directly from Db4oTool.exe by calling<br />
                    <table border="0" cellpadding="3" cellspacing="0" width="100%">
                        <tr>
                            <td class="lg">
                                <code>Db4oTool.exe -help</code></td>
                        </tr>
                    </table>
                    <br />
                    <br />
                    Options may be grouped into 4 categories:<br />
                    <br />
                    <a href="Enhancement.html#EnhancementModes">Enhancement Modes</a><br />
                    <a href="Enhancement.html#TargetTypeSpecification">Target types (classes) specification</a><br />
                    <a href="Enhancement.html#OutputMode">Output related options</a><br />
                    <a href="Enhancement.html#MiscOptions">Misc Options</a><br />
                    <br />
                    <a name="EnhancementModes"></a>
                    <br />
                    <ul>
                        <a name="outline231"></a>
                        <br />
                        <h2>
                            16.3.1. Enhancement Modes</h2>
                        <br />
                        With the options in this group you can specify which type of instrumentation you
                        want to apply (either <a href="TransparentActivation.html#TransparentActivation">Transparent
                            Activation </a>or <a href="Enhancement.html#NQOptimization">Native Queries Optimization</a>
                        or both)<br />
                        <br />
                        &nbsp; &nbsp; &nbsp;-ta : Add Transparent Activation Support<br />
                        &nbsp; &nbsp; &nbsp;-nq : Optimize Native Queries<br />
                        &nbsp; &nbsp;&nbsp; -instrumentation:PARAM : Use your own instrumentation type
                        <br />
                        <br />
                        <br />
                        <a name="TargetTypeSpecification"></a>
                        <br />
                        <a name="outline232"></a>
                        <br />
                        <h2>
                            16.3.2. Target types (classes) specification</h2>
                        <br />
                        When enhancing an assembly it's possible to enhance all or some of its types through
                        the following options:<br />
                        <br />
                        &nbsp; &nbsp; &nbsp;-by-attribute:PARAM &nbsp; &nbsp;Filter types to be instrumented
                        by attribute<br />
                        &nbsp; &nbsp; &nbsp;-by-filter:PARAM &nbsp; &nbsp; &nbsp; &nbsp;Custom type filter<br />
                        &nbsp; &nbsp; &nbsp;-by-name:PARAM &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;Filter
                        types by name (with regular expression syntax)<br />
                        &nbsp; &nbsp; &nbsp;-not &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
                        &nbsp; &nbsp;Negates the last filter<br />
                        <br />
                        Note that these filters specifies which types should be included in the enhancement
                        process. enhanced. If you want to filter out (i.e, to not enhance some types) you
                        can specify <b>-not</b>option.<br />
                        <br />
                        <b>-by-name</b>filter expects a regular expression and will include each type whose
                        fully qualified name matches this regular expression.
                        <br />
                        <br />
                        <a name="OutputMode"></a>
                        <br />
                        <a name="outline233"></a>
                        <br />
                        <h2>
                            16.3.3. Output related options</h2>
                        &nbsp; &nbsp;&nbsp;
                        <br />
                        Output related options<br />
                        <br />
                        &nbsp; &nbsp; &nbsp;-debug &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
                        &nbsp;Preserve debugging information<br />
                        &nbsp; &nbsp; &nbsp;-fake &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
                        &nbsp; Fake operation mode, assembly won't be written<br />
                        <br />
                        <br />
                        <a name="MiscOptions"></a>
                        <br />
                        <a name="outline234"></a>
                        <br />
                        <h2>
                            16.3.4. Misc Options</h2>
                        <br />
                        &nbsp; &nbsp; &nbsp;-case-sensitive &nbsp; &nbsp; &nbsp; &nbsp; Case sensitive queries<br />
                        &nbsp; &nbsp; &nbsp;-? -help &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;Show
                        this help list<br />
                        &nbsp; &nbsp; &nbsp;-usage &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
                        &nbsp;Show usage syntax and exit<br />
                        &nbsp; -v -verbose &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;Verbose
                        operation mode<br />
                        &nbsp; -V -version &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;Display
                        version and licensing information<br />
                        &nbsp; &nbsp; &nbsp;-vv &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;
                        &nbsp; &nbsp; Pretty verbose operation mode<br />
                        <br />
                        <a name="NQOptimization"></a>
                        <br />
                    </ul>
                    <a name="outline235"></a>
                    <br />
                    <h2>
                        16.4. Native Query Optimization</h2>
                    <br />
                    The Native Query optimizer is still under development to eventually "understand"
                    all valid C# constructs. Current optimization supports the following constructs
                    well:<br />
                    <br />
                    - compile-time constants<br />
                    - simple member access<br />
                    - primitive comparisons<br />
                    - equality operator<br />
                    - #Contains()/#StartsWith()/#EndsWith() for Strings<br />
                    - boolean expressions<br />
                    - arbitrary method calls (including property accessors) on predicate fields (without
                    any arguments)<br />
                    - candidate methods composed of the above<br />
                    - chained combinations of the above<br />
                    <br />
                    Note that the current implementation does not support polymorphism yet.<br />
                    <br />
                    If optimization is turned off or not possible for some reason, a Native Query will
                    be executed by instantiating all objects, using <a href="Evaluations.html#Evaluations">
                        SODA Evaluations</a>. Naturally performance will not be as good in this case,
                    but queries will still deliver correct results.<br />
                    <br />
                    <ul>
                        <a name="outline236"></a>
                        <br />
                        <h2>
                            16.4.1. Native Query Optimization on CompactFramework 2.0</h2>
                        <br />
                        Due to some platform limitations, CompactFramework 2.0 users using the convenient
                        delegate based Native Query syntax that want their queries to be optimized are required
                        to run the Db4oTool.exe command line utility on their assemblies prior to deploying
                        them.
                        <br />
                        <br />
                        The Db4oTool.exe utility, which can be found in the /bin folder of this distribution
                        is required because the CompactFramework API does not expose any of the delegate
                        metadata needed by the Native Query optimizer.<br />
                        <br />
                        The tool can be easily integrated inside Visual Studio.NET 2005 as a Post Build
                        tool by following the simple steps below:<br />
                        <br />
                        - Right click the project you want to enable Native Query optimization for<br />
                        - Select<b>'Properties'</b><br />
                        - In the Properties Page select the<b>'Build Events'</b>tab<br />
                        - In the<b>'Post-build event command line'</b>text box insert the following text
                        <b>"<path-to-your-db4o-installation></path-to-your-db4o-installation>/bin/Db4oTool.exe
                            -nq $(TargetPath)"</b> without the quotes and replacing
                        <path-to-your-db4o-installation>
</path-to-your-db4o-installation>
                        to the correct value for your system.<br />
                        <br />
                        <a name="outline237"></a>
                        <br />
                        <h2>
                            16.4.2. Monitoring optimization</h2>
                        <br />
                        To monitor optimization you can attach event handlers to the IObjectContainer:<br />
                        <br />
                        <table border="0" cellpadding="3" cellspacing="0" width="100%">
                            <tr>
                                <td class="lg">
                                    <code>NativeQueryHandler handler = ((ObjectContainerBase)container).GetNativeQueryHandler();<br />
                                        handler.QueryExecution += OnQueryExecution;<br />
                                        handler.QueryOptimizationFailure += OnQueryOptimizationFailure;</code></td>
                            </tr>
                        </table>
                        <br />
                        <br />
                        <br />
                        <br />
                        <p align="center">
                            <a href="http://www.db4o.com/" target="_top"><small>www.db4o.com</small></a></p>
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                        <br />
                    </ul>
                </ul>
            </td>
        </tr>
    </table>
</div>
